Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(cmd-api-server): swagger.json endpoints #1994

Merged
merged 3 commits into from
Sep 17, 2023

Conversation

charellesandig
Copy link
Contributor

@charellesandig charellesandig commented Apr 27, 2022

commit ff29e94 (HEAD -> pr/charellesandig/1994, charellesandig/issue1877)
Author: Peter Somogyvari [email protected]
Date: Wed Sep 13 16:39:42 2023 -0700

feat(cmd-api-server): add GetOpenApiSpecV1Endpoint (HTTP GET)

The new endpoint can serve up the OpenAPI specification file of the
API server via a get request without any parameters needed.

Under the hood it uses the re-usable common base endpoint class that
we've recently added to the core package.

The test case at this file path demonstrates how to use it via the API
client:
`packages/cactus-cmd-api-server/src/test/typescript/unit/get-open-api-spec-v1-endpoint.test.ts`

Signed-off-by: Peter Somogyvari <[email protected]>

commit ebd0abf
Author: Peter Somogyvari [email protected]
Date: Wed Sep 13 14:09:30 2023 -0700

feat(connector-besu): add GetOpenApiSpecV1Endpoint (HTTP GET)

The new endpoint can serve up the OpenAPI specification file of the
plugin via a get request without any parameters needed.

Under the hood it uses the re-usable common base endpoint class that
we've recently added to the core package.

The test case at this file path demonstrates how to use it via the API
client:
`packages/cactus-plugin-ledger-connector-besu/src/test/typescript/
unit/get-open-api-spec-v1-connector-besu.test.ts`

Signed-off-by: Peter Somogyvari <[email protected]>

commit 4b541ec
Author: Peter Somogyvari [email protected]
Date: Wed Sep 13 13:48:20 2023 -0700

feat(cactus-core): add GetOpenApiSpecV1EndpointBase<S, P> class

This is the pre-requisite to finishing the task at
https://github.com/hyperledger/cacti/issues/1877

Having this generic endpoint class available will allow us to send in
another commit which then uses it to create the Open API spec endpoints
in all the plugin classes.

Example usage of the generic class looks like this:

```typescript
import {
  GetOpenApiSpecV1EndpointBase,
  IGetOpenApiSpecV1EndpointBaseOptions,
} from "@hyperledger/cactus-core";

import { Checks, LogLevelDesc } from "@hyperledger/cactus-common";
import { IWebServiceEndpoint } from "@hyperledger/cactus-core-api";

import OAS from "../../json/openapi.json";

export const OasPathGetOpenApiSpecV1 =
  OAS.paths[
    "/api/v1/plugins/@hyperledger/cactus-plugin-ledger-connector-besu/get-open-api-spec"
  ];

export type OasPathTypeGetOpenApiSpecV1 = typeof OasPathGetOpenApiSpecV1;

export interface IGetOpenApiSpecV1EndpointOptions
  extends IGetOpenApiSpecV1EndpointBaseOptions<
    typeof OAS,
    OasPathTypeGetOpenApiSpecV1
  > {
  readonly logLevel?: LogLevelDesc;
}

export class GetOpenApiSpecV1Endpoint
  extends GetOpenApiSpecV1EndpointBase<typeof OAS, OasPathTypeGetOpenApiSpecV1>
  implements IWebServiceEndpoint
{
  public get className(): string {
    return GetOpenApiSpecV1Endpoint.CLASS_NAME;
  }

  constructor(public readonly options: IGetOpenApiSpecV1EndpointOptions) {
    super(options);
    const fnTag = `${this.className}#constructor()`;
    Checks.truthy(options, `${fnTag} arg options`);
  }
}
```

And the associated OpenAPI specification's paths entry:

```json
"/api/v1/plugins/@hyperledger/cactus-plugin-ledger-connector-besu/get-open-api-spec": {
  "get": {
    "x-hyperledger-cactus": {
      "http": {
        "verbLowerCase": "get",
        "path": "/api/v1/plugins/@hyperledger/cactus-plugin-ledger-connector-besu/get-open-api-spec"
      }
    },
    "operationId": "getOpenApiSpecV1",
    "summary": "Retrieves the .json file that contains the OpenAPI specification for the plugin.",
    "parameters": [],
    "responses": {
      "200": {
        "description": "OK",
        "content": {
          "application/json": {
            "schema": {
              "type": "string"
            }
          }
        }
      }
    }
  }
},
```

Signed-off-by: Peter Somogyvari <[email protected]>

Copy link
Contributor

@jagpreetsinghsasan jagpreetsinghsasan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just one question here. @petermetz do we also need to have to patch our test cases with relevant code, to include testing of this endpoint as well?

@petermetz
Copy link
Contributor

Just one question here. @petermetz do we also need to have to patch our test cases with relevant code, to include testing of this endpoint as well?

@jagpreetsinghsasan Yes, there will have to be test coverage for these endpoints as well but I don't want to get into that yet because we are still working out the fundamental acceptance criteria such as re-usability (see my submitted change request above for details).

Copy link
Contributor

@petermetz petermetz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@charellesandig Please write a test case that shows and verifies the endpoint working correctly at runtime.

Copy link
Contributor

@petermetz petermetz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM - I just did a complete refactor so now it's closer to the original acceptance criteria but it still doesn't cover all the plugins just the API server and the Besu connector. This is enough to establish a pattern based on which we can create smaller future PRs that make it happen for the rest of the plugins that have web services and Open API specs of their own.

@petermetz petermetz dismissed jagpreetsinghsasan’s stale review September 14, 2023 00:17

No longer applies, the original change request has been addressed implicitly by going in a slightly different direction (see the details in the updated PR description)

@petermetz petermetz enabled auto-merge (rebase) September 14, 2023 00:18
@petermetz petermetz force-pushed the issue1877 branch 5 times, most recently from 13f666a to 439691d Compare September 14, 2023 19:15
@petermetz
Copy link
Contributor

petermetz commented Sep 15, 2023

Note to self: These are the crash logs for the two jobs (cactus-test-api-client and cactus-test-plugin-consortium-manual) that are timing out for some reason. It's likely a bug with the plugin registry initialization logic of the API server that was changed a little bit to make it more flexible (more flexible = more bug prone as usual...)

2023-09-14T20-29-18-cacti-ci-crash-2.log

2023-09-14T20-29-18-cacti-ci-crash.log

This is the pre-requisite to finishing the task at
https://github.com/hyperledger/cacti/issues/1877

Having this generic endpoint class available will allow us to send in
another commit which then uses it to create the Open API spec endpoints
in all the plugin classes.

Example usage of the generic class looks like this:

```typescript
import {
  GetOpenApiSpecV1EndpointBase,
  IGetOpenApiSpecV1EndpointBaseOptions,
} from "@hyperledger/cactus-core";

import { Checks, LogLevelDesc } from "@hyperledger/cactus-common";
import { IWebServiceEndpoint } from "@hyperledger/cactus-core-api";

import OAS from "../../json/openapi.json";

export const OasPathGetOpenApiSpecV1 =
  OAS.paths[
    "/api/v1/plugins/@hyperledger/cactus-plugin-ledger-connector-besu/get-open-api-spec"
  ];

export type OasPathTypeGetOpenApiSpecV1 = typeof OasPathGetOpenApiSpecV1;

export interface IGetOpenApiSpecV1EndpointOptions
  extends IGetOpenApiSpecV1EndpointBaseOptions<
    typeof OAS,
    OasPathTypeGetOpenApiSpecV1
  > {
  readonly logLevel?: LogLevelDesc;
}

export class GetOpenApiSpecV1Endpoint
  extends GetOpenApiSpecV1EndpointBase<typeof OAS, OasPathTypeGetOpenApiSpecV1>
  implements IWebServiceEndpoint
{
  public get className(): string {
    return GetOpenApiSpecV1Endpoint.CLASS_NAME;
  }

  constructor(public readonly options: IGetOpenApiSpecV1EndpointOptions) {
    super(options);
    const fnTag = `${this.className}#constructor()`;
    Checks.truthy(options, `${fnTag} arg options`);
  }
}
```

And the associated OpenAPI specification's paths entry:

```json
"/api/v1/plugins/@hyperledger/cactus-plugin-ledger-connector-besu/get-open-api-spec": {
  "get": {
    "x-hyperledger-cactus": {
      "http": {
        "verbLowerCase": "get",
        "path": "/api/v1/plugins/@hyperledger/cactus-plugin-ledger-connector-besu/get-open-api-spec"
      }
    },
    "operationId": "getOpenApiSpecV1",
    "summary": "Retrieves the .json file that contains the OpenAPI specification for the plugin.",
    "parameters": [],
    "responses": {
      "200": {
        "description": "OK",
        "content": {
          "application/json": {
            "schema": {
              "type": "string"
            }
          }
        }
      }
    }
  }
},
```

Signed-off-by: Peter Somogyvari <[email protected]>
The new endpoint can serve up the OpenAPI specification file of the
plugin via a get request without any parameters needed.

Under the hood it uses the re-usable common base endpoint class that
we've recently added to the core package.

The test case at this file path demonstrates how to use it via the API
client:
`packages/cactus-plugin-ledger-connector-besu/src/test/typescript/
unit/get-open-api-spec-v1-connector-besu.test.ts`

Signed-off-by: Peter Somogyvari <[email protected]>
@petermetz petermetz closed this Sep 15, 2023
auto-merge was automatically disabled September 15, 2023 22:43

Pull request was closed

@petermetz petermetz deleted the issue1877 branch September 15, 2023 22:43
@petermetz petermetz restored the issue1877 branch September 15, 2023 22:49
@petermetz petermetz reopened this Sep 15, 2023
@petermetz petermetz enabled auto-merge (rebase) September 15, 2023 23:04
The new endpoint can serve up the OpenAPI specification file of the
API server via a get request without any parameters needed.

Under the hood it uses the re-usable common base endpoint class that
we've recently added to the core package.

The test case at this file path demonstrates how to use it via the API
client:
`packages/cactus-cmd-api-server/src/test/typescript/unit/get-open-api-spec-v1-endpoint.test.ts`

Signed-off-by: Peter Somogyvari <[email protected]>
@petermetz petermetz merged commit aeebbd4 into hyperledger-cacti:main Sep 17, 2023
109 of 135 checks passed
@petermetz petermetz deleted the issue1877 branch September 17, 2023 01:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
API_Server enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants